home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 11 / Cream of the Crop 11-1.iso / program / swmp141.zip / C.DOC < prev    next >
Text File  |  1995-12-12  |  6KB  |  145 lines
  1.  
  2.  ┌────────────────────────────────────────────────────────────────────────────┐
  3.  │ Module Player V1.41     (c) 1994,1995 by Lord Excess of Sound Wizards Int. │
  4.  └────────────────────────────────────────────────────────────────────────────┘
  5.  
  6.  
  7.  
  8.         USING THE SWMP DRIVERS WITH 'BORLAND C'
  9.         ───────────────────────────────────────
  10.  
  11.          First of all you have to unzip the files of the included
  12.         archive C_SDK.ZIP into an existing directory.
  13.         The files you need in any case are:
  14.  
  15.               MODPLAY.INC           : interface to drivers
  16.               MOD_DRV.OBJ           : all sound drivers
  17.  
  18.          The rest are example files, which can be important to
  19.         understand things better. Now you have to perform two steps to
  20.         use all mod-routines:
  21.  
  22.          1. Add the following expression to your source code:
  23.  
  24.               #include "modplay.inc"
  25.  
  26.          2. For a successfull link of the drivers you best open a
  27.             project file, else you have to study the syntax of your
  28.             linker... After that add the file "mod_drv.obj" and of
  29.             course all of your source files.
  30.  
  31.          At program start you have to initialize one of the drivers
  32.         using the following subroutine:
  33.  
  34. ┌──INIT DRIVER─────────────────────────────────────────────────────────────────
  35. │       void MOD_Init(unsigned int Driver, unsigned int Port,
  36. │                     unsigned char IRQ, unsigned char DMA)
  37. │         -> Select and initialize driver for sound output
  38. │
  39. │            Driver = Detection         (0) :  Port = 0
  40. │                                              IRQ  = 0
  41. │                                              DMA  = 0
  42. │
  43. │                   = SoundBlaster      (1) :  Port = SB base address (x220..)
  44. │                                              IRQ  = SB IRQ#
  45. │                                              DMA  = 1 (always)
  46. │
  47. │                   = SoundBlaster_Pro  (2) :  Port = SBP base address
  48. │                                              IRQ  = SBP IRQ#
  49. │                                              DMA  = SBP DMA channel
  50. │
  51. │                   = Gravis_UltraSound (3) :  Port = GUS base address
  52. │                                              IRQ  = GF1 IRQ#
  53. │                                              DMA  = MIDI IRQ# !!
  54. └
  55.  
  56.          A very powerful hardware detection is able to detect any
  57.         supported soundcard with all required settings. So in general
  58.         the easiest way to init the drivers is:
  59.  
  60.                 MOD_Init(Detection,0,0,0);
  61.  
  62.          If all fails you can override detection and select one of the
  63.         drivers by yourself, but in this case you have to know (or ask
  64.         for) the settings of an installed soundcard.
  65.  
  66.  
  67.          If you want to know if initialisation was successfull, have a
  68.         look at the variable (unsigned int) Soundcard, which will
  69.         contain the output device:
  70.  
  71.               0:        no sound available
  72.               1:        SoundBlaster            [ 22.2 kHz mono     ]
  73.               2:        SoundBlaster Pro        [ 21.7 kHz stereo   ]
  74.               3:        Gravis UltraSound       [ 44.1 kHz +stereo+ ]
  75.  
  76.          You do not have to handle this variable. You can also call the
  77.         driver's subfunctions even if no soundcard was detected,
  78.         nothing will happen in this case.
  79.  
  80.          At program end the unit selfrestores any altered interrupt
  81.         vectors etc.
  82.  
  83.          The following functions are now available:
  84.         (Note: The first two functions are enough to playback a mod !!!)
  85.  
  86. ┌──LOAD MODULE─────────────────────────────────────────────────────────────────
  87. │       void Mod_Load(char far *File_Name)
  88. │         -> Stops possible sound output, loads module file into memory,
  89. │            but does not start playing. If successfull the variable
  90. │            (unsigned int) Channels will contain the number of channels,
  91. │            else zero.
  92. └
  93. ┌──PLAY MODULE─────────────────────────────────────────────────────────────────
  94. │       void Mod_Play(unsigned int Looping)
  95. │         -> Starts playing previously loaded song. If looping is zero,
  96. │            song is played only once, else continuously.
  97. └
  98. ┌──STOP MODULE─────────────────────────────────────────────────────────────────
  99. │       void Mod_Stop(void)
  100. │         -> Stops sound output at once.
  101. └
  102. ┌──MAIN VOLUME─────────────────────────────────────────────────────────────────
  103. │       void Mod_Volume(unsigned char Volume)
  104. │         -> Changes the driver's main volume setting. Valid values are
  105. │            between 0 (lowest) and 64 (loudest).
  106. └
  107. ┌──STATUS──────────────────────────────────────────────────────────────────────
  108. │       unsigned int Mod_Status(void)
  109. │         -> Returns 1 if sound is being played, else 0.
  110. └
  111. ┌──GET POSITION────────────────────────────────────────────────────────────────
  112. │       unsigned int Mod_Position(void)
  113. │         -> Returns 256*PatternNumber+LineNumber. Can be useful to
  114. │            syncronize a special graphic effect to the sound.
  115. └
  116. ┌──JUMP BACK───────────────────────────────────────────────────────────────────
  117. │       void Mod_Rewind(void)
  118. │         -> Decreases current songposition. No effect in first pattern.
  119. └
  120. ┌──JUMP FORWARD────────────────────────────────────────────────────────────────
  121. │       void Mod_Forward(void)
  122. │         -> Increases current songposition. No effect in last pattern.
  123. └
  124. ┌──PEAKS───────────────────────────────────────────────────────────────────────
  125. │       void Mod_Peak(void)
  126. │         -> Updates the array Peaks by copying the driver's volume
  127. │            setting (0..64) of each channel. The number of channels
  128. │            can be found in the variable Channels (WORD) and is either
  129. │            four, six or eight.
  130. └
  131.  
  132.  
  133.  
  134.          In general it remains to be said that you can do as much error
  135.         checking as you like, but it is not necessary. In a demo or
  136.         intro for example you do not care if there is sound available
  137.         to the grafix you produce on the screen (in most cases). But in
  138.         a player it is evident that you need to have any sounddevice at
  139.         all to output the sound! The best way is to take a look at the
  140.         example programs. Have a lot of fun!
  141.  
  142.  
  143.                                                Lord Excess in Dezember '95
  144. 
  145.